home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / libs / intuisup.lha / Intuisup / Library / intuisup.doc < prev    next >
Text File  |  1992-07-20  |  20KB  |  478 lines
  1.         A few sentences to ISUP
  2.         -----------------------
  3.  
  4. All ISUP objects are created from special data structures (struct xxxData)
  5. via library functions (Createxxx). Some of these functions expect (a pointer
  6. to) an ARRAY of data structures to create multiple objects with one call.
  7. These arrays are terminated with an entry (data structure) with it's type
  8. member (xxx_Type) set to the special value INTUISUP_DATA_END (0).
  9. DON'T FORGET THIS TERMINATION ENTRY OR YOU'RE VISITED BY THE GURU.
  10.  
  11. The creation functions return a pointer (APTR) to the internal data
  12. environment according to these ISUP objects. This pointer is used later as
  13. paramter for the other functions to access the object data.
  14. THE POINTERS TO INTERNAL DATA OF THE DIFFERENT ISUP OBJECTS ARE ALL OF THE
  15. SAME TYPE (APTR), SO DON'T CONFUSE WITH THEM.
  16.  
  17. Now a few words to the functions of ISUP library:
  18.  
  19. APTR IGetRenderInfo(struct Screen  *screen, USHORT flags)
  20.     screen - ptr to screen the ISUP object should be displayed on or
  21.          NULL for the workbench screen
  22.     flags - RENDER_INFO_FLAG_xxx
  23.  
  24.     Returns a pointer to an internal data structure with some visual
  25.     infos needed for creation of ISUP objects. Use the SAME pointer
  26.     (only ONE call of IGetRenderInfo for all ISUP objects displayed on
  27.     the SAME screen) as parameter APTR ri to the ISUP functions. This
  28.     data structure MUST be released with the function IFreeRenderInfo
  29.     before closing library.
  30.  
  31. VOID IFreeRenderInfo(APTR ri)
  32.     ri - pointer to internal data structure returned by IGetRenderInfo
  33.  
  34.     Releases memory for internal data structure allocated by
  35.     IGetRenderInfo.
  36.  
  37. struct Window  *IOpenWindow(APTR ri, struct NewWindow  *nw, USHORT flags)
  38.     ri - pointer to internal data structure returned by IGetRenderInfo
  39.     nw - pointer to initialized NewWindow structure
  40.     flags - OPEN_WINDOW_FLAG_xxx
  41.  
  42.     Manipulates NewWindow structure according to given flags and opens
  43.     window from it.
  44.  
  45. VOID IClearWindow(APTR ri, struct Window  *win, USHORT left_edge,
  46.          USHORT top_edge, USHORT width, USHORT height, USHORT flags)
  47.     ri - pointer to internal data structure returned by IGetRenderInfo
  48.     win - pointer to window opened by (I)OpenWindow
  49.     left_edge, top_edge, width, height - dimension of area to clear
  50.     flags - CLEAR_WIDNOW_FLAG_xxx
  51.  
  52.     Clears area of given window according to visual infos (APTR ri). The
  53.     area will be clipped to the window dimension if necessary.
  54.  
  55. VOID ICloseWindow(struct Window  *win, BOOL more_windows)
  56.     win - pointer to window opened by (I)OpenWindow
  57.     more_windows - TRUE if user port of window shared with other windows
  58.  
  59.     Closes window in a savely manner (all IntuiMessages are replyed,
  60.     user port is only closed if not shared, ...).
  61.  
  62. struct AvailFontsHeader    *IAvailFonts(APTR ri)
  63.     ri - pointer to internal data structure returned by IGetRenderInfo
  64.  
  65.     Creates a list of all available fonts (ROM + disk) and saves this in
  66.     the internal data structure (APTR ri).
  67.  
  68. struct TextAttr  *IAskFont(APTR ri, struct TextAttr  *ta)
  69.     ri - pointer to internal data structure returned by IGetRenderInfo
  70.     ta - pointer to initialized structure with text attributes
  71.  
  72.     Check if given font exists in internal font list (APTR ri) created
  73.     with IAvailFonts.
  74.  
  75. struct TextFont  *IOpenFont(APTR ri, struct TextAttr  *ta)
  76.     ri - pointer to internal data structure returned by IGetRenderInfo
  77.     ta - pointer to initialized structure with text attributes
  78.  
  79.     Open font according to given TextAttr structure from internal font
  80.     list (APTR ri).
  81.  
  82. VOID IDisplayTexts(APTR ri, struct Window  *win, struct TextData  *td,
  83.            SHORT hoffset, SHORT voffset, BYTE **language_text_array)
  84.     ri - pointer to internal data structure returned by IGetRenderInfo
  85.     win - pointer to window opened by (I)OpenWindow
  86.     td - pointer to ARRAY of initialized TextData structures
  87.     hoffset, voffset - offsets added to positions of ALL texts
  88.     language_text_array - pointer to string pointer array created with
  89.                   IBuildLanguageTextArray or NULL
  90.  
  91.     Displays texts described in given data structure array. If given
  92.     language_text_array is not NULL then td_Text doesn't contain a
  93.     pointer to string but an offset of the string pointer in given array
  94.     with pointers to text in foreign languages.
  95.  
  96. USHORT IPrintText(APTR ri, struct Window  *win, BYTE *text, USHORT left_edge,
  97.      USHORT top_edge, USHORT type, USHORT flags, struct TextAttr  *text_attr)
  98.     ri - pointer to internal data structure returned by IGetRenderInfo
  99.     win - pointer to window opened by (I)OpenWindow
  100.     text - pointer to string with text
  101.     left_edge, top_edge - position of text on diplay
  102.     type - TEXT_DATA_TYPE_xxx
  103.     flags - TEXT_DATA_FLAG_xxx
  104.     text_attr - font used for text
  105.  
  106.     Displays text at given position.
  107.  
  108. USHORT IConvertUnsignedDec(ULONG num, BYTE *buffer, USHORT flags)
  109.     num - number to be converted
  110.     buffer - pointer to buffer for converted number
  111.     flags - CONVERT_FLAG_xxx
  112.  
  113.     Convert binary number to text string in unsigned decimal format.
  114.  
  115. USHORT IConvertSignedDec(LONG num, BYTE *buffer, USHORT flags)
  116.     num - number to be converted
  117.     buffer - pointer to buffer for converted number
  118.     flags - CONVERT_FLAG_xxx
  119.  
  120.     Convert binary number to text string in signed decimal format.
  121.  
  122. USHORT IConvertHex(ULONG num, BYTE *buffer, USHORT flags)
  123.     num - number to be converted
  124.     buffer - pointer to buffer for converted number
  125.     flags - CONVERT_FLAG_xxx
  126.  
  127.     Convert binary number to text string in hexa decimal format.
  128.  
  129. USHORT IConvertBin(ULONG num, BYTE *buffer, USHORT flags)
  130.     num - number to be converted
  131.     buffer - pointer to buffer for converted number
  132.     flags - CONVERT_FLAG_xxx
  133.  
  134.     Convert binary number to text string in binary format.
  135.  
  136. VOID IDisplayBorders(APTR ri, struct Window  *win, struct BorderData  *bd,
  137.                            SHORT hoffset, SHORT voffset)
  138.     ri - pointer to internal data structure returned by IGetRenderInfo
  139.     win - pointer to window opened by (I)OpenWindow
  140.     td - pointer to ARRAY of initialized BorderData structures
  141.     hoffset, voffset - offsets added to positions of ALL texts
  142.  
  143.     Displays borders described in given data structure array.
  144.  
  145. VOID IDrawBorder(APTR ri, struct Window  *win, USHORT left_edge,
  146.           USHORT top_edge, USHORT width, USHORT height, USHORT type)
  147.     ri - pointer to internal data structure returned by IGetRenderInfo
  148.     win - pointer to window opened by (I)OpenWindow
  149.     left_edge, top_edge, width, height - dimension of border
  150.     type - BORDER_DATA_TYPE_xxx
  151.  
  152.     Draws border at given position on display.
  153.  
  154. APTR ICreateGadgets(APTR ri, struct GadgetData  *gd, SHORT hoffset,
  155.                   SHORT voffset, BYTE **language_text_array)
  156.     ri - pointer to internal data structure returned by IGetRenderInfo
  157.     gd - pointer to ARRAY of initialized GadgetData structures
  158.     hoffset, voffset - offsets added to positions of ALL texts
  159.     language_text_array - pointer to string pointer array created with
  160.                   IBuildLanguageTextArray or NULL
  161.  
  162.     Create internal data structure for ISUP gadgets from given array of
  163.     data structures. This function DON'T display any object. Displaying
  164.     will be done with IDisplayGadgets. Internal data structure MUST be
  165.     released with IFreeGadgets. If given language_text_array are not
  166.     NULL then gd_Text doesn't contain a pointer to string but an offset
  167.     of the string pointer in given array with pointers to text in foreign
  168.     languages.
  169.  
  170. VOID IFreeGadgets(APTR gl)
  171.     gl - pointer to internal data structure returned by ICreateGadgets
  172.  
  173.     Releases memory for internal data structure allocated by
  174.     ICreateGadgets. If gadgets are currently displayed then they MUST be
  175.     removed with IRemoveGadgets first.
  176.  
  177. VOID IDisplayGadgets(struct Window  *win, APTR gl)
  178.     win - pointer to window opened by (I)OpenWindow
  179.     gl - pointer to internal data structure returned by ICreateGadgets
  180.  
  181.     Displays all gadgets from given internal data structure (gadgets now
  182.     are selectable). To remove gadgets from display use IRemoveGadgets
  183.     (gadgets aren't selectable any more).
  184.  
  185. VOID IRefreshGadgets(APTR gl)
  186.     gl - pointer to internal data structure returned by ICreateGadgets
  187.  
  188.     Refresh images of all gadgets from given internal data structure.
  189.     ONLY NEEDED FOR WINDOWREFRESH OR NEWSIZE IDCMP EVENTS.
  190.  
  191. VOID IModifyGadget(APTR gl, USHORT data_entry, LONG left_edge, LONG top_edge,
  192.                           ULONG width, ULONG height)
  193.     gl - pointer to internal data structure returned by ICreateGadgets
  194.     data_entry - offset (in array of GadgetData structures) of gadget to
  195.              modify
  196.     left_edge, top_edge, width, height - new dimension of gadget or
  197.                          USE_CURRENT_VALUE for old value
  198.  
  199.     Repositions and/or resizes a gadget. All gadgets can be repositioned
  200.     but only some gadgets can be modified: buttons, sliders and
  201.     scrollers. NO ADDITIONAL REFRESH NEEDED.
  202.  
  203. ULONG ISetGadgetAttributes(APTR gl, USHORT data_entry, ULONG flag_mask,
  204.              ULONG flag_bits, ULONG data1, ULONG data2, VOID *data3)
  205.     gl - pointer to internal data structure returned by ICreateGadgets
  206.     data_entry - offset (in array of GadgetData structures) of gadget to
  207.              change attributes
  208.     flag_mask - mask with bits set for flag bits to change
  209.     flag_bits - new flag bits (only bits with flag mask bit set are
  210.             changed)
  211.     data1, data2, data3 - new values for appropriate union gd_SpecialData
  212.                   or USE_CURENT_VALUE for old value
  213.  
  214.     Changes flags or special data and returns OLD value of a gadget. Not
  215.     all special data members can be changed of different gadgets. Some
  216.     are fixed while creating. NO ADDITIONAL REFRESH NEEDED.
  217.  
  218.  
  219. VOID IActivateInputGadget(APTR gl, USHORT data_entry)
  220.     gl - pointer to internal data structure returned by ICreateGadgets
  221.     data_entry - offset (in array of GadgetData structures) of gadget to
  222.              activate
  223.  
  224.     Activates an input gadget (string or integer gadget).
  225.  
  226. struct Gadget  *IGadgetAddress(APTR gl, USHORT data_entry)
  227.     gl - pointer to internal data structure returned by ICreateGadgets
  228.     data_entry - offset (in array of GadgetData structures) of gadget to
  229.              get pointer of its standard gadget structure
  230.  
  231.     Returns pointer to the appropriate standard gadget structure. This
  232.     function is normally not used, because no access to the standard
  233.     gadget structures is required. All changes to ISUP objects MUST be
  234.     performed via ISetGadgetAttributes().
  235.  
  236. struct Window  *IRemoveGadgets(APTR gl)
  237.     gl - pointer to internal data structure returned by ICreateGadgets
  238.  
  239.     Removes all gadgets belonging to given internal data structure from
  240.     display (gadgets aren't selectable any more). Pointer to window
  241.     gadgets displayed before is returned.
  242.  
  243. struct IntuiMessage  *IGetMsg(struct MsgPort  *uport)
  244.     uport - window's user port
  245.  
  246.     MUST be used instead of Exec's GetMsg to handle all actions belonging
  247.     to ISUP objects. For all events produced by ISUP objects a modified
  248.     IntuiMessage structure will be returned. Some of their members are
  249.     (mis)used for special ISUP data:
  250.  
  251.         Class = ISUP_ID -> need to identify an modified ISUP message
  252.         Code = id of the appropriate ISUP object -> offset of object
  253.                data structure in array of GadgetData structures
  254.                given to ICreateGadgets()
  255.         IAddress = value returned from ISUP object, e.g. state (0|1)
  256.                of check gadget, count of count gadget,...
  257.                ATTENTION: for string gadgets IAddress contains
  258.                       a pointer to the gadget's input buffer,
  259.                       so no ptr to gad->StringInfo.Buffer
  260.                       needed
  261.         SpecialLink = internal ptr returned by ICreateGadgets()
  262.                   according to appropriate ISUP object
  263.                   ATTENTION: if more than one lists with ISUP
  264.                      objects displayed on the same
  265.                      window, SpecialLink must be checked
  266.                      first for the list the ISUP object
  267.                      belongs to
  268.  
  269.     All other members of the IntuiMessage structure contains their
  270.     normal values. All special IntuiMessage    structures MUST be replied
  271.     with IReplyMsg instead of Exec's ReplyMsg. Normal IntuiMessage can
  272.     replied with this function too.
  273.  
  274.     Example:
  275.  
  276.        struct IntuiMessage *im;
  277.  
  278.        while (im = IGetMsg(win->UserPort)) {
  279.                ^
  280.                |
  281.           if (im->Class == ISUP_ID) {
  282.          ULONG value;
  283.  
  284.          /* Handle event from ISUP object */
  285.          switch (im->Code) {
  286.             case 0 :    /* first object in GadgetData array */
  287.                value = (ULONG)im->IAddress;   /* value returned from this object */
  288.                break;
  289.                  :
  290.                  :
  291.             case n :    /* n-th object in GadgetData array */
  292.                value = (ULONG)im->IAddress;   /* value returned from this object */
  293.                break;
  294.          }
  295.           } else {
  296.  
  297.          /* Handle normal IDCMP events */
  298.             :
  299.             :
  300.           }
  301.           IReplyMsg(im);
  302.           ^
  303.           |
  304.        }
  305.  
  306. VOID IReplyMsg(struct IntuiMessage  *imsg)
  307.     imsg - IntuiMessage received with IGetMsg
  308.  
  309.     Replys special IntuiMessage built by IGetMsg (Class == ISUP_ID).
  310.     Normal IntuiMessage can replied with this function too.
  311.  
  312. UBYTE IConvertRawKeytoASCII(struct IntuiMessage  *imsg)
  313.     imsg - IntuiMessage received with IGetMsg
  314.  
  315.     Returns ASCII code of given RAWKEY IntuiMessage or ZERO if no
  316.     ASCII character.
  317.  
  318. BOOL IAutoRequest(struct Window  *req_win, BYTE *title, BYTE *body_text,
  319.                BYTE *pos_text, BYTE *neg_text, LONG pos_idcmp_flags,
  320.      LONG neg_idcmp_flags, USHORT req_flags, BYTE **language_text_array)
  321.     req_win - pointer to window opened by (I)OpenWindow or NULL for
  322.           window on workbench screen
  323.     title - pointer to title string for requester window or NULL for
  324.         default title
  325.     body_text - pointer to text string for requester body
  326.     pos_text - pointer to text string for positive gadget or NULL for no
  327.            positive gadget
  328.     neg_text - pointer to text string for negative gadget or NULL for no
  329.            negative gadget
  330.     pos_idcmp_flags - IDCMP flags for activating positive gadget
  331.     neg_idcmp_flags - IDCMP flags for activating negative gadget
  332.     req_flags - REQ_DATA_FLAG_xxx
  333.     language_text_array - pointer to string pointer array created with
  334.                   IBuildLanguageTextArray or NULL
  335.  
  336.     Displays an auto requester from given data and waits for it's
  337.     termination with the positive or negative gadget. In body text a new
  338.     line is started with `\n'. If given language_text_array is not NULL
  339.     then td_Text doesn't contain a pointer to string but an offset of
  340.     the string pointer in given array with pointers to text in foreign
  341.     languages.
  342.  
  343. APTR IDisplayRequester(struct Window  *req_win, struct RequesterData  *rd,
  344.                          BYTE **language_text_array)
  345.     req_win - pointer to window opened by (I)OpenWindow or NULL for
  346.           window on workbench screen
  347.     rd - pointer to initialized RequesterData structure
  348.     language_text_array - pointer to string pointer array created with
  349.                   IBuildLanguageTextArray or NULL
  350.  
  351.     Displays a requester defined by given RequesterData structure. All
  352.     other gadgets displayed on window the requester window (req_win)
  353.     opened from are disabled till removing of requester. So any
  354.     IntuiMessages with Class == ISUP_ID received by
  355.     IGetMsg(req_win->UserPort) come from requester. If given
  356.     language_text_array is not NULL then td_Text doesn't contain a
  357.     pointer to string but an offset of the string pointer in given array
  358.     with pointers to text in foreign languages. Pointer to internal
  359.     data structure belonging to requester is returned. Requester MUST be
  360.     removed from display with IRemoveRequester.
  361.  
  362. VOID IRemoveRequester(APTR rl)
  363.     rl - pointer to internal data structure returned by IDisplayRequester
  364.  
  365.     Removes requester belonging to given internal data structure from
  366.     display. All gadgets disabled by IDisplayGadgets are reenabled now.
  367.     
  368. APTR ICreateMenu(APTR ri, struct Window  *win, struct MenuData  *md,
  369.                struct TextAttr  *ta, BYTE **language_text_array)
  370.     ri - pointer to internal data structure returned by IGetRenderInfo
  371.     win - pointer to window opened by (I)OpenWindow
  372.     md - pointer to ARRAY of initialized MenuData structures
  373.     ta - pointer to initialized structure with text attributes
  374.     language_text_array - pointer to string pointer array created with
  375.                   IBuildLanguageTextArray or NULL
  376.  
  377.     Create internal data structure for a menu from given array of data
  378.     structures. This function DON'T display the menu. Displaying will be
  379.     done with IAttachMenu. Internal data structure MUST be released with
  380.     IFreeMenu. If given language_text_array are not NULL then md_Text
  381.     doesn't contain a pointer to string but an offset of the string
  382.     pointer in given array with pointers to text in foreign languages.
  383.     Pointer to internal data structure belonging to menu is returned.
  384.  
  385. VOID IAttachMenu(struct Window  *win, APTR ml)
  386.     win - pointer to window opened by (I)OpenWindow
  387.     ml - pointer to internal data structure returned by ICreateMenu
  388.  
  389.     Make menu built with ICreateMenu available by attaching it to given
  390.     window. Menu MUST be removed with IRemoveMenu.
  391.  
  392. struct MenuItem  *IMenuItemAddress(APTR ml, USHORT menu_num)
  393.     ml - pointer to internal data structure returned by ICreateMenu
  394.     menu_num - offset (in array of MenuData structures) of menu item
  395.            to get address
  396.  
  397.     Return pointer to normal MenuItem structure of specified menu item.
  398.  
  399. struct Window  *IRemoveMenu(APTR ml)
  400.     ml - pointer to internal data structure returned by ICreateMenu
  401.  
  402.     Remove menu attached with IAttachMenu from display.
  403.  
  404. VOID IFreeMenu(APTR ml)
  405.     ml - pointer to internal data structure returned by ICreateMenu
  406.  
  407.     Releases memory for internal data structure allocated by
  408.     ICreateMenu. If menu is currently attached then it MUST be removed
  409.     with IRemoveMenu first.
  410.  
  411. struct FileData  *IOpenTextFile(BYTE *name, USHORT read_buffer_size,
  412.                       USHORT line_buffer_size, USHORT flags)
  413.     name - pointer to string with file name
  414.     read_buffer_size - size (in bytes) of buffer used for reading text
  415.                file
  416.     line_buffer_size - number of bytes used for longest line of text
  417.     flags - TEXT_FILE_FLAG_xxx
  418.  
  419.     Opens given text file and returns pointer to data structure with
  420.     allocated buffers. This structure MUST be freed with ICloseTextFile.
  421.  
  422. SHORT IReadTextLine(struct FileData  *fd)
  423.     fd - pointer to internal data structure returned by IOpenTextFile
  424.  
  425.     Read next line from text file opened with IOpenTextFile. This line
  426.     can be found in given FileData structure.
  427.  
  428. VOID ICloseTextFile(struct FileData  *fd)
  429.     fd - pointer to internal data structure returned by IOpenTextFile
  430.  
  431.     Close text file opened with IOpenTextFile and releases allocated
  432.     buffers.
  433.  
  434. BYTE **IBuildLanguageTextArray(BYTE *name, USHORT entries)
  435.     name - pointer to string with name of file with language texts
  436.     entries - number of text entries in file
  437.  
  438.     Parse given text file and return pointer to array of text strings
  439.     read from language file. This array MUST be released with
  440.     IFreeLanguageTextArray.
  441.  
  442. BYTE *IGetLanguageText(BYTE *text, BYTE **text_array)
  443.     text - offset (in array of text strings) of language text (starting
  444.            with 1 instead of 0!!!)
  445.     text_array - pointer to array of text strings created by
  446.              IBuildLanguageTextArray
  447.  
  448.     Returns specified entry from within text pointer array created with
  449.     IBuildLanguageTextArray.
  450.  
  451. VOID IFreeLanguageTextArray(BYTE **text_array)
  452.     text_array - pointer to array of text strings created by
  453.              IBuildLanguageTextArray
  454.  
  455.     Releases memory of array created with IBuildLanguageTextArray.
  456.  
  457. VOID IChangeMousePointer(struct Window  *win, struct PointerData  *pd)
  458.     win - pointer to window opened by (I)OpenWindow
  459.     pd - pointer to initialized PointerData structure or NULL for
  460.          busy mouse pointer
  461.  
  462.     Replace current mouse pointer of selected window with one described
  463.     in given data structure. Old mouse pointer will be saved and can be
  464.     restored later with IRestoreMousePointer.
  465.  
  466. VOID IRestoreMousePointer(struct Window  *win)
  467.     win - pointer to window opened by (I)OpenWindow
  468.  
  469.     Restore old mouse pointer saved with IChangeMousePointer.
  470.  
  471. VOID IMoveMousePointer(struct Window  *win, SHORT x, SHORT y, BOOL button)
  472.     win - pointer to window opened by (I)OpenWindow
  473.     x, y - new position (relative to upper left corner of given
  474.            window!!!) for mouse pointer
  475.     button - TRUE for left mouse button pressed
  476.  
  477.     Move mouse pointer of given window to new position.
  478.